<html>

    <head>
        <link href="style.css" rel="stylesheet" type="text/css"/>
        <title>Atlanta Lending Library - Design</title>
    </head>

    <body>

        <div class="content">

            <h1>Atlanta Lending Library - Design</h1>
            
            <h2>Introduction</h2>
            
            <p>
                The Atlanta project started life as an example of how to use NHibernate
                and Spring.Net.  It has evolved into a sample application of how to combine
                best practice techniques and best of breed technologies to create an application.
            </p>
            <p>
                The project currently uses the following technologies:
            </p>
            <ul>
                <li>NAnt;</li>
                <li>NUnit;</li>
                <li>NHibernate;</li>
                <li>Spring.Net;</li>
                <li>Silverlight;</li>
                <li>NCover;</li>
                <li>Firebird (RDBMS).</li>
            </ul>
            
            <p>
                This remaining sections of this document describe the Development Methodology,
                Architecture (patterns and implementation),
                and functional design of the Atlanta Lending Library.
            </p>

            <h2>Development Methodology</h2>
            <p>
                The development on Atlanta does not subscribe to a single methodology (e.g., XP, SCRUM)
                but instead borrows techniques from methodologies in the Agile/Lean arena.
            </p>
            <p>
                In addition, the nature of development on an example project doesn't lend itself
                to the sort of pressures and deadlines that demonstrate the advantages of Agile
                practices in the field.
                As such, the development of Atlanta sticks to the core principals of:
            </p>
            <ul>
                <li>Test Driven Development (TDD);</li>
                <li>Continuous Integration (CI);</li>
                <li>Collective Code Ownership;</li>
                <li>Aggressive Refactoring.</li>
            </ul>
            <p>
                We have a suite of tests using NUnit, an automated build using NAnt,
                built in test-coverage checked in the build using NCover, and we endeavour
                to ensure that every Subversion check-in results in a working end-to-end build.
            </p>
            <p>
                In reality we normally subscribe to any of a range of techniques when creating software,
                including:
            </p>
            <ul>
                <li>Iterative and Incremental Development (IID);
                    <ul><li>with preference to shorter iterations - e.g., 1 week</li></ul></li>
                <li>Time Boxing;</li>
                <li>Requirements Freeze;</li>
                <li>YAGNI;</li>
                <li>Sustainable Development;</li>
                <li>Whole Team Together;</li>
                <li>Pair Programming;</li>
                <li>e.t.c., ...</li>
            </ul>

            <h2>Architecture</h2>
            
            <p>
                The architecture of Atlanta is described in two parts:
            </p>
            <ul>
                <li>
                    Part 1 describes the architecture using Design Patterns.
                    Note that these patterns describe the architecture of the system
                    in a technology agnostic fashion - they could just as easily be describing
                    a system implemented in Java;
                </li>
                <li>
                    Part 2 desribes the (.NET specific) technologies used to implement the patterns discussed in Part 1.
                </li>
            </ul>

            <h3>Part 1 - Architectural Patterns</h3>
            
            <p>
                The Atlanta architecture is a
                Layered Application with three principal layers:
            </p>
            <ul>
                <li>Business Logic;</li>
                <li>Services;</li>
                <li>Presentation.</li>
            </ul>
            
            <h4>Business Logic Layer</h4>
            <p>
                The core business logic is implemented using a
                <a target="_blank" href="http://martinfowler.com/eaaCatalog/domainModel.html">Domain Model</a>.
            </p>
            <p>
                The model is persisted in a relational database using a
                <a target="_blank" href="http://martinfowler.com/eaaCatalog/dataMapper.html">Data Mapper</a>.
                <a target="_blank" href="http://martinfowler.com/eaaCatalog/lazyLoad.html">Lazy Load</a>
                allows the model to traverse associations without explicit data
                access code, while an
                <a target="_blank" href="http://martinfowler.com/eaaCatalog/identityMap.html">Identity Map</a>
                maintains reference equality throughout the domain.
                Changes to the model are tracked (and ultimately persisted) using a
                <a target="_blank" href="http://martinfowler.com/eaaCatalog/unitOfWork.html">Unit of Work</a>.
            </p>
            <p>
                Data access is hidden behind a
                <a target="_blank" href="http://martinfowler.com/eaaCatalog/repository.html">Repository</a>,
                and a
                <a target="_blank" href="http://martinfowler.com/eaaCatalog/queryObject.html">Query Object</a>
                is used to allow interrogation of the database in an object-oriented fashion
                while keeping the model free of the internal mechanism.
            </p>

            <h4>Services Layer</h4>
            <p>
                A <a target="_blank" href="http://martinfowler.com/eaaCatalog/serviceLayer.html">Service Layer</a>
                is employed as an application boundary where aspects can be applied
                consistently across a range of methods (AOP).
                While the Service Layer is aware of persistence mechanisms, it is kept
                free of business logic and merely acts as an entry point into the
                Domain Model.
            </p>
            <p>
                A <a target="_blank" href="http://martinfowler.com/eaaCatalog/remoteFacade.html">Remote Facade</a>
                exposes the coarse grained interface across the wire.
            </p>

            <h4>Presentation Layer</h4>
            <p>
                The presentation logic uses a variation on
                Model View Controller,
                specifically
                <a target="_blank" href="http://martinfowler.com/eaaDev/PassiveScreen.html">Passive View</a>.
                The controller talks to the model using the Remote Facade exposed
                from the services layer, and is responsible for controlling the
                state and input of the widgets from the view.
            </p>
            
            <h3>Part 2 - Pattern Implementations</h3>
            <p>
                This section details the specific .NET technologies used to implement the
                architecture described in Part 1 above.
            </p>

            <h4>Business Logic Layer</h4>
            <p>
                The relational database is implemented using the embedded client for
                <a target="_blank" href="http://www.firebirdsql.org/">Firebird RDBMS</a>.
            </p>
            <p>
                The Domain Model is implemented using regular POCOs.  The object-relational-mapping
                is implemented using NHibernate which combines:  Data Mapper, Lazy Load, Identity Map, and Unit of Work.
            </p>
            <p>
                The Repository is implemented by a thin wrapper exposing a subset of the NHibernate ISession interface,
                and the NHibernate ICriteria interface provides the Query Object implementation.
            </p>

            <h4>Services Layer</h4>
            <p>
                The core Service Layer logic is implemented using a POCO.  This class is proxied using
                Spring.Net's AOP framework to implement interception and apply the following advice
                to the methods:
            </p>
            <ul>
                <li>Logging (using log4net - TODO);</li>
                <li>Auditing (using the NHibernate IInterceptor interface - TODO);</li>
                <li>Transaction Handling (using the NHibernate ISession interface);</li>
                <li>Exception Handling (rolling back transactions, and handling serialisation of exceptions).</li>
            </ul>
            <p>
                The Remote Facade is exposed using WCF, and is hosted in IIS.  This process combines both
                the Services Layer and the Business Logic Layer.
            </p>

            <h4>Presentation Layer</h4>
            <p>
                The Passive View is implemented in Silverlight, and exposed to the controller through
                interfaces.
            </p>
            <p>
                The presentation controller is a regular POCO that communicates with the view's interfaces,
                and with the WCF service
                through a generated proxy (custom generated using
                <a target="_blank" href="http://www.olegsych.com/2007/12/text-template-transformation-toolkit/">T4</a>
                templates), allowing the controllers to be cross compiled to the regular .NET
                framework and tested in isolation using NUnit.
            </p>

            <h2>Analysis Model</h2>
            <p>
                The Analysis Model provides a ubiquitous language that is structure around
                the Atlanta Domain Model.  This language is used consistently when discussing
                Atlanta functionality, and throughout the use cases.
            </p>
            <p>
                The nouns (which often correspond to a class in the Domain Model) are described in
                the following sub-sections.
            </p>

            <h3>User</h3>
            <table class="umlClass">
                <tr><th>User</th></tr>

                <tr class="umlAttribute"><td>Login : string</td></tr>
                <tr class="umlAttribute"><td>Password : string</td></tr>
                <tr class="umlAttribute"><td>Name : string</td></tr>
                <tr class="umlAttribute"><td>Workplace : (0..1) Library</td></tr>

                <tr class="umlSeparator"><td></td></tr>

                <tr class="umlOperation"><td>Validate(password)</td></tr>
                <tr class="umlOperation"><td>RegisterWorkplace(library)</td></tr>
            </table>
            <p>
                Human actors have a corresponding User in the system.  Each User has a
                'login' and 'password', and a human identifiable 'name'.  A User can optionally
                register a 'workplace' that is the Library at which they control Media.
            </p>
            <ul>
                <li>User logins are unique throughout the system;</li>
                <li>User names are unique throughout the system.</li>
            </ul>

            <h3>Library</h3>
            <table class="umlClass">
                <tr><th>Library</th></tr>

                <tr class="umlAttribute"><td>Name : string</td></tr>
                <tr class="umlAttribute"><td>Description : string</td></tr>
                <tr class="umlAttribute"><td>OwnedMedia : (0..*) Media</td></tr>

                <tr class="umlSeparator"><td></td></tr>

                <tr class="umlOperation"><td>Add(media)</td></tr>
                <tr class="umlOperation"><td>Remove(media)</td></tr>
            </table>
            <p>
                Libraries are containers for Media, and provide a workplace for Users.
            </p>
            <ul>
                <li>Library names are unique throughout the system.</li>
            </ul>

            <h3>Media</h3>
            <table class="umlClass">
                <tr><th>Media</th></tr>
                <tr class="umlAttribute"><td>Title : string</td></tr>
                <tr class="umlAttribute"><td>Type : (Book | CD | DVD)</td></tr>
                <tr class="umlAttribute"><td>Summary : string</td></tr>
                <tr class="umlAttribute"><td>LoanHistory : (0..*) Loan</td></tr>

                <tr class="umlSeparator"><td></td></tr>

                <tr class="umlOperation"><td>LoanTo(Customer)</td></tr>
                <tr class="umlOperation"><td>ReturnToLibrary()</td></tr>
            </table>
            <p>
                Media are contained in a Library and are loaned to Customers.
                Media records a history of its loan to each Customer.
            </p>
            <ul>
                <li>The combination of Media title and type are unique within a Library;</li>
                <li>A Media can have at most 1 Loan without a return date.</li>
            </ul>

            <h3>Customer</h3>
            <table class="umlClass">
                <tr><th>Customer</th></tr>
                <tr class="umlAttribute"><td>Name : string</td></tr>
                <tr class="umlAttribute"><td>PostalCode : string</td></tr>
                <tr class="umlAttribute"><td>AddressDetail : string</td></tr>
                <tr class="umlAttribute"><td>Telephone : string</td></tr>

                <tr class="umlSeparator"><td></td></tr>

            </table>
            <p>
                Customers correspond to a human that can be loaned Media.  Address detail is
                used to flesh out any information required to complete an address (e.g., it might
                be enough to have a postal code and just a house number in the address detail).
            </p>
            <ul>
                <li>The combination of Customer name and postal code are unique.</li>
            </ul>

            <h3>Loan</h3>
            <table class="umlClass">
                <tr><th>Loan</th></tr>

                <tr class="umlAttribute"><td>Loaned : datetime</td></tr>
                <tr class="umlAttribute"><td>Returned : (0..1) datetime</td></tr>
                <tr class="umlAttribute"><td>Media : Media</td></tr>
                <tr class="umlAttribute"><td>Customer : Customer</td></tr>

                <tr class="umlSeparator"><td></td></tr>

                <tr class="umlOperation"><td>Returned()</td></tr>
            </table>
            <p>
                A Loan describes a relationship between a Customer and a Media detailing when
                the Customer was loaned the Media, and when it was returned to the Library.
            </p>
            <ul>
                <li>When a Loan is initially created, there is no 'returned' date.</li>
            </ul>


            <h2>Use Cases</h2>
            <p>
                The Use Cases define the behavioural requirements for the Atlanta Lending Library.
                The Use Cases are
                <a target="_blank" href="http://en.wikipedia.org/wiki/Use_case#Degree_of_detail">fully dressed</a>,
                and use the language of the Analysis Model defined above.
            </p>
            <p>
                The Use Cases use the following actors:
            </p>
            <ul>
                <li>User: superclass of human actors;</li>
                <li>Administrator (inherits User): performs administrative actions on the system;</li>
                <li>Librarian (inherits User): uses the system to perform lending tasks on the system.</li>
            </ul>
            
            <h3>Links to Use Cases</h3>
            <h4>Opening</h4>
            <ul>
                <li><a href="UseCases/Opening/Logon.xml">Logon</a></li>
                <li><a href="UseCases/Opening/LibrarianRegistersWorkplace.xml">Librarian Registers Workplace</a></li>
            </ul>
            <h4>Administration</h4>
            <ul>
                <li><a href="UseCases/Administration/ConfigureUsers.xml">Configure Users</a></li>
                <li><a href="UseCases/Administration/ConfigureLibraries.xml">Configure Libraries</a></li>
            </ul>
            <h4>Lending</h4>
            <ul>
                <li><a href="UseCases/Lending/ManageLibraryMedia.xml">Manage Library Media</a></li>
                <li><a href="UseCases/Lending/LibrarianLoansMediaToCustomer.xml">Librarian Loans Media to Customer</a></li>
                <li><a href="UseCases/Lending/CustomerReturnsMediaToLibrary.xml">Customer Returns Media to Library</a></li>
            </ul>

        </div>

    </body>

</html>

